p-timeout

What is p-timeout?

The p-timeout package is a utility that allows you to wrap a Promise with a timeout, after which a specified exception is thrown if the promise does not resolve or reject before the timeout period elapses. This is useful for ensuring that your application can handle situations where a Promise might take too long to complete, or when you want to enforce a strict timing policy for certain operations.

What are p-timeout's main functionalities?

Timeout a Promise

This feature allows you to set a timeout for a Promise. If the Promise does not resolve or reject within the specified time, it will be rejected with a TimeoutError.

const pTimeout = require('p-timeout');

const doSomething = () => new Promise(resolve => setTimeout(resolve, 2000));

pTimeout(doSomething(), 1000).then(() => console.log('Resolved')).catch(error => console.log('Timed out:', error.message));

Custom Timeout Error

This feature allows you to specify a custom error message for the timeout. If the Promise times out, it will be rejected with a TimeoutError that contains your custom message.

const pTimeout = require('p-timeout');
const TimeoutError = pTimeout.TimeoutError;

const doSomething = () => new Promise(resolve => setTimeout(resolve, 2000));

pTimeout(doSomething(), 1000, 'Operation timed out').then(() => console.log('Resolved')).catch(error => {
  if (error instanceof TimeoutError) {
    console.log('Custom timeout message:', error.message);
  }
});

Clearing the Timeout

This feature allows you to clear the timeout before it occurs. This is useful if the conditions of your operation change and you no longer require the timeout.

const pTimeout = require('p-timeout');

const doSomething = () => new Promise(resolve => setTimeout(resolve, 2000));

const promiseWithTimeout = pTimeout(doSomething(), 1000);
promiseWithTimeout.then(() => console.log('Resolved')).catch(error => console.log('Timed out:', error.message));

// Later, if you decide you no longer want the timeout:
pTimeout.clear(promiseWithTimeout);

Other packages similar to p-timeout

promise-timeout

The promise-timeout package offers similar functionality to p-timeout, allowing you to add a timeout to a Promise. It differs in API design and error handling specifics.

bluebird

Bluebird is a full-featured Promise library that includes a .timeout() method for timing out promises. It is more comprehensive than p-timeout but also larger in size and scope.

async-timeout

The async-timeout package is similar to p-timeout but is designed specifically for use with async functions and the async/await syntax.

README

p-timeout

Timeout a promise after a specified amount of time

Install

$ npm install p-timeout

Usage

const delay = require('delay');
const pTimeout = require('p-timeout');

const delayedPromise = delay(200);

pTimeout(delayedPromise, 50).then(() => 'foo');
//=> [TimeoutError: Promise timed out after 50 milliseconds]

API

pTimeout(input, ms, [message | fallback])

Returns a decorated input that times out after ms time.

input

Type: Promise

Promise to decorate.

ms

Type: number

Milliseconds before timing out.

message

Type: string Error
Default: 'Promise timed out after 50 milliseconds'

Specify a custom error message or error.

If you do a custom error, it's recommended to sub-class pTimeout.TimeoutError.

fallback

Type: Function

Do something other than rejecting with an error on timeout.

You could for example retry:

const delay = require('delay');
const pTimeout = require('p-timeout');

const delayedPromise = () => delay(200);

pTimeout(delayedPromise(), 50, () => {
	return pTimeout(delayedPromise(), 300);
});

pTimeout.TimeoutError

Exposed for instance checking and sub-classing.

Related

• delay - Delay a promise a specified amount of time
• p-min-delay - Delay a promise a minimum amount of time
• p-retry - Retry a promise-returning function
• More…

License

MIT © Sindre Sorhus